# Multi-Environment Builds

Rsbuild supports building outputs for multiple environments at the same time. You can use [environments](/config/environments) to build multiple environments in parallel and set a different Rsbuild config for each environment.

## What is environment

The `environment` refers to the runtime environment for build output. Common environments include browsers, Node.js, and Workers. Rsbuild allows you to define any environment names and set build options for each environment individually.

A typical scenario is server-side rendering (SSR). You can define two environments, `web` and `node`, where the build targets ([output.target](/config/output/target)) are `web` and `node`. These are used for client-side rendering (CSR) and server-side rendering (SSR) scenarios.

You can also define different environments for the same build target, for example:

- Define `rsc` and `ssr` environments, both targeting `node`, used separately for React Server Components and SSR.
- Define `desktop` and `mobile` environments, both targeting `web`, used separately for desktop and mobile browsers.

Without the `environments` configuration, you would need to define multiple configurations for these scenarios and run multiple independent Rsbuild builds. Now, with the `environments` configuration, you can complete the build for multiple outputs in a single Rsbuild run (Rsbuild achieves this using Rspack's `MultiCompiler`).

In Rsbuild, each `environment` is associated with an Rsbuild configuration, an Rspack configuration, and a set of build outputs. Rsbuild plugin developers can customize the build process for a specified environment based on the `environment` name, such as modifying Rsbuild or Rspack configurations, registering or removing plugins, adjusting Rspack rules, and viewing assets information.

## Environment configs

Rsbuild supports defining different Rsbuild configs for each environment through [environments](/config/environments).

For example, if your project wants to support the SSR function, you need to define different configs for client and SSR respectively. You can define a web and node environment respectively.

```ts title=rsbuild.config.ts
export default {
  environments: {
    // Configure the web environment for browsers
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        // Use 'web' target for the browser outputs
        target: 'web',
      },
      resolve: {
        alias: {
          '@common': './src/client/common',
        },
      },
    },
    // Configure the node environment for SSR
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        // Use 'node' target for the Node.js outputs
        target: 'node',
      },
      resolve: {
        alias: {
          '@common': './src/server/common',
        },
      },
    },
  },
};
```

### Config Merging

If you configure `environments`, Rsbuild will merge the config in `environments` with the outer base config. When merging, the config in `environments` has higher priority.

In the example above, after merging the configs, Rsbuild generates two standalone environment configs for building web and node environments.

- **web environments config**: Generated by merging base config with `environments.web`
- **node environments config**: Generated by merging base config with `environments.node`

Then, Rsbuild will use these environments configs to internally generate two Rspack configs and execute a single build using Rspack’s MultiCompiler.

### Debug Config

When you execute the command `npx rsbuild inspect` in the project root directory, you will find the following output:

- rsbuild.config.[name].mjs: Indicates the Rsbuild config used for a certain environment during build.
- rspack.config.[name].mjs: Indicates the Rspack config corresponding to a certain environment when building.

```bash
➜ npx rsbuild inspect

Inspect config succeed, open following files to view the content:

  - Rsbuild Config (web): /project/dist/.rsbuild/rsbuild.config.web.mjs
  - Rsbuild Config (node): /project/dist/.rsbuild/rsbuild.config.node.mjs
  - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs
  - Rspack Config (node): /project/dist/.rsbuild/rspack.config.node.mjs
```

## Default environment

When environments is not specified, Rsbuild will by default create an environment with the same name based on the currently target type (the value of [output.target](/config/output/target)).

```ts title=rsbuild.config.ts
export default {
  output: {
    target: 'web',
  },
};
```

The above config is equivalent to a simplification of the following config:

```ts title=rsbuild.config.ts
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
  },
};
```

## Specify environment build

By default, Rsbuild will build all environments in the Rsbuild configuration when you execute `rsbuild dev` or `rsbuild build`. You can build only the specified environment via `--environment <name>`.

```bash
# Build for all environments by default
rsbuild dev

# Build for the web environment
rsbuild dev --environment web

# Build for the web and ssr environments
rsbuild dev --environment web --environment node

# Build multiple environments can be shortened to:
rsbuild dev --environment web,node
```

## Add plugins for specified environment

Plugins configured through the [plugins](/config/plugins) field support running in all environments. If you want a plugin to run only in a specified environment, you can configure the plugin in the specified `environment`.

For example, enable the React plugin only in the web environment:

```ts title=rsbuild.config.ts
import { pluginReact } from '@rsbuild/plugin-react';

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
      plugins: [pluginReact()],
    },
    node: {
      output: {
        target: 'node',
      },
    },
  },
};
```

If you are a plugin developer, you can view [Developing environment plugins](/plugins/dev/index#environment-plugin) for details.

## Plugin API

### Update environment config

Rsbuild supports modifying or adding environment config through the [modifyRsbuildConfig](/plugins/dev/hooks#modifyrsbuildconfig) hook.

```ts
const myPlugin = () => ({
  setup: (api) => {
    api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
      return mergeRsbuildConfig(config, {
        environments: {
          web1: {
            source: {
              entry: {
                index: './src/web1/index',
              },
            },
          },
        },
      });
    });
  },
});
```

### Configuring a specific environment

Rsbuild supports modifying the Rsbuild config of a specific environment through the [modifyEnvironmentConfig](/plugins/dev/hooks#modifyenvironmentconfig) hook.

```ts
const myPlugin = () => ({
  setup: (api) => {
    api.modifyEnvironmentConfig((config, { name }) => {
      if (name !== 'web') {
        return config;
      }
      config.html.title = 'My Default Title';
    });
  },
});
```

## Environment context

[Environment context](/api/javascript-api/environment-api#environment-context) is a read-only object that provides some context infos about the current environment. Rsbuild supports obtaining environment context information in plugin hooks.

For some plugin hooks related to the build environment (such as [modifyRspackConfig](/plugins/dev/hooks#modifyrspackconfig) and [modifyBundlerChain](/plugins/dev/hooks#modifybundlerchain)), Rsbuild supports obtaining the current environment context through the `environment` parameter.

```ts
const myPlugin = () => ({
  setup: (api) => {
    api.modifyRspackConfig((rspackConfig, { environment }) => {
      if (environment.name === 'node') {
        // do some thing
      }
    });
  },
});
```

For some global plugin hooks (such as [onDevCompileDone](/plugins/dev/hooks#ondevcompiledone), [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver), etc.), Rsbuild supports obtaining the context of all environments through the `environments` parameter.

```ts
const myPlugin = () => ({
  setup: (api) => {
    api.onDevCompileDone(({ environments }) => {
      environments.forEach((environment) => {
        console.log('environment', environment);
      });
    });
  },
});
```

## Environment API

Rsbuild server provides a series of APIs related to the build environment. Users can operate the build artifacts in a specific environment on the server side through the Rsbuild [environment API](/api/javascript-api/environment-api#environment-api).

You can use the environment API in [Rsbuild DevMiddleware](/config/dev/setup-middlewares) or [Custom Server](/api/javascript-api/instance#rsbuildcreatedevserver).

For example, you can quickly implement an SSR function through the Rsbuild environment API in development mode:

```ts
import express from 'express';
import { createRsbuild, loadConfig } from '@rsbuild/core';

const serverRender = (serverAPI) => async (_req, res) => {
  const indexModule = await serverAPI.environments.node.loadBundle('index');

  const markup = indexModule.render();

  const template = await serverAPI.environments.web.getTransformedHtml('index');

  const html = template.replace('<!--app-content-->', markup);

  res.writeHead(200, {
    'Content-Type': 'text/html',
  });
  res.end(html);
};

export async function startDevServer() {
  const { content } = await loadConfig({});

  // Init Rsbuild
  const rsbuild = await createRsbuild({
    rsbuildConfig: content,
  });

  const app = express();

  // Create Rsbuild DevServer instance
  const rsbuildServer = await rsbuild.createDevServer();

  const serverRenderMiddleware = serverRender(rsbuildServer);

  app.get('/', async (req, res, next) => {
    try {
      await serverRenderMiddleware(req, res, next);
    } catch (err) {
      logger.error('SSR render error, downgrade to CSR...\n', err);
      next();
    }
  });

  // Apply Rsbuild’s built-in middlewares
  app.use(rsbuildServer.middlewares);

  // ...
}
```

For detailed usage, please refer to: [SSR + Express Example](https://github.com/rspack-contrib/rspack-examples/tree/main/rsbuild/ssr-express).

## Add environment dependencies

By default, Rsbuild builds all environments in parallel. If an environment in your project depends on other environments to be compiled first, you can add the name of the environment you need to depend on to Rspack's [dependencies](https://rspack.dev/config/other-options#dependencies) configuration.

For example, the node environment depends on the web environment to be compiled first. You can add the following configuration:

```ts title=rsbuild.config.ts
export default {
  environments: {
    web: {},
    node: {
      tools: {
        rspack: {
          dependencies: ['web'],
        },
      },
    },
  },
};
```
